home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / Shape.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  14.4 KB  |  315 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Shape.java    1.15 98/10/19
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. import java.awt.geom.AffineTransform;
  18. import java.awt.geom.PathIterator;
  19. import java.awt.geom.Point2D;
  20. import java.awt.geom.Rectangle2D;
  21.  
  22. /**
  23.  * The <code>Shape</code> interface provides definitions for objects 
  24.  * that represent some form of geometric shape.  The <code>Shape</code>
  25.  * is described by a {@link PathIterator} object, which can express the 
  26.  * outline of the <code>Shape</code> as well as a rule for determining 
  27.  * how the outline divides the 2D plane into interior and exterior 
  28.  * points.  Each <code>Shape</code> object provides callbacks to get the 
  29.  * bounding box of the geometry, determine whether points or 
  30.  * rectangles lie partly or entirely within the interior
  31.  * of the <code>Shape</code>, and retrieve a <code>PathIterator</code>
  32.  * object that describes the trajectory path of the <code>Shape</code>
  33.  * outline.
  34.  * <p>
  35.  * <b>Definition of insideness:</b>
  36.  * A point is considered to lie inside a 
  37.  * <code>Shape</code> if and only if:
  38.  * <ul>
  39.  * <li> it lies completely
  40.  * inside the<code>Shape</code> boundary <i>or</i> 
  41.  * <li>
  42.  * it lies exactly on the <code>Shape</code> boundary <i>and</i> the 
  43.  * space immediately adjacent to the
  44.  * point in the increasing <code>X</code> direction is 
  45.  * entirely inside the boundary <i>or</i>
  46.  * <li>
  47.  * it lies exactly on a horizontal boundary segment <b>and</b> the
  48.  * space immediately adjacent to the point in the 
  49.  * increasing <code>Y</code> direction is inside the boundary.
  50.  * </ul>
  51.  *
  52.  * @see java.awt.geom.PathIterator
  53.  * @see java.awt.geom.AffineTransform
  54.  * @see java.awt.geom.FlatteningPathIterator
  55.  * @see java.awt.geom.GeneralPath
  56.  *
  57.  * @version 1.19 06/24/98
  58.  * @author Jim Graham
  59.  */
  60. public interface Shape {
  61.     /**
  62.      * Returns an integer {@link Rectangle} that completely encloses the
  63.      * <code>Shape</code>.  Note that there is no guarantee that the
  64.      * returned <code>Rectangle</code> is the smallest bounding box that
  65.      * encloses the <code>Shape</code>, only that the <code>Shape</code>
  66.      * lies entirely within the indicated  <code>Rectangle</code>.  The
  67.      * returned <code>Rectangle</code> might also fail to completely
  68.      * enclose the <code>Shape</code> if the <code>Shape</code> overflows
  69.      * the limited range of the integer data type.  The 
  70.      * <code>getBounds2D</code> method generally returns a
  71.      * tighter bounding box due to its greater flexibility in
  72.      * representation.
  73.      * @return an integer <code>Rectangle</code> that completely encloses
  74.      *                 the <code>Shape</code>.
  75.      * @see #getBounds2D
  76.      */
  77.     public Rectangle getBounds();
  78.  
  79.     /**
  80.      * Returns a high precision and more accurate bounding box of
  81.      * the <code>Shape</code> than the <code>getBounds</code> method.
  82.      * Note that there is no guarantee that the returned 
  83.      * {@link Rectangle2D} is the smallest bounding box that encloses 
  84.      * the <code>Shape</code>, only that the <code>Shape</code> lies 
  85.      * entirely within the indicated <code>Rectangle2D</code>.  The 
  86.      * bounding box returned by this method is usually tighter than that 
  87.      * returned by the <code>getBounds</code> method and never fails due 
  88.      * to overflow problems since the return value can be an instance of 
  89.      * the <code>Rectangle2D</code> that uses double precision values to 
  90.      * store the dimensions.
  91.      * @return an instance of <code>Rectangle2D</code> that is a
  92.      *                 high-precision bounding box of the <code>Shape</code>.
  93.      * @see #getBounds
  94.      */
  95.     public Rectangle2D getBounds2D();
  96.  
  97.     /**
  98.      * Tests if the specified coordinates are inside the boundary of the 
  99.      * <code>Shape</code>.
  100.      * @param x, y the specified coordinates
  101.      * @return <code>true</code> if the specified coordinates are inside 
  102.      *         the <code>Shape</code> boundary; <code>false</code>
  103.      *         otherwise.
  104.      */
  105.     public boolean contains(double x, double y);
  106.  
  107.     /**
  108.      * Tests if a specified {@link Point2D} is inside the boundary
  109.      * of the <code>Shape</code>.
  110.      * @param p a specified <code>Point2D</code>
  111.      * @return <code>true</code> if the specified <code>Point2D</code> is 
  112.      *          inside the boundary of the <code>Shape</code>;
  113.      *        <code>false</code> otherwise.
  114.      */
  115.     public boolean contains(Point2D p);
  116.  
  117.     /**
  118.      * Tests if the interior of the <code>Shape</code> intersects the 
  119.      * interior of a specified rectangular area.
  120.      * The rectangular area is considered to intersect the <code>Shape</code> 
  121.      * if any point is contained in both the interior of the 
  122.      * <code>Shape</code> and the specified rectangular area.
  123.      * <p>
  124.      * This method might conservatively return <code>true</code> when:
  125.      * <ul>
  126.      * <li>
  127.      * there is a high probability that the rectangular area and the
  128.      * <code>Shape</code> intersect, but
  129.      * <li>
  130.      * the calculations to accurately determine this intersection
  131.      * are prohibitively expensive.
  132.      * </ul>
  133.      * This means that this method might return <code>true</code> even
  134.      * though the rectangular area does not intersect the <code>Shape</code>.
  135.      * The {@link java.awt.geom.Area Area} class can be used to perform 
  136.      * more accurate computations of geometric intersection for any 
  137.      * <code>Shape</code> object if a more precise answer is required.
  138.      * @param x, y the coordinates of the specified rectangular area
  139.      * @param w the width of the specified rectangular area
  140.      * @param h the height of the specified rectangular area
  141.      * @return <code>true</code> if the interior of the <code>Shape</code> and
  142.      *         the interior of the rectangular area intersect, or are
  143.      *         both highly likely to intersect and intersection calculations 
  144.      *         would be too expensive to perform; <code>false</code> otherwise.
  145.      * @see java.awt.geom.Area
  146.      */
  147.     public boolean intersects(double x, double y, double w, double h);
  148.  
  149.     /**
  150.      * Tests if the interior of the <code>Shape</code> intersects the 
  151.      * interior of a specified <code>Rectangle2D</code>.
  152.      * This method might conservatively return <code>true</code> when:
  153.      * <ul>
  154.      * <li>
  155.      * there is a high probability that the <code>Rectangle2D</code> and the
  156.      * <code>Shape</code> intersect, but
  157.      * <li>
  158.      * the calculations to accurately determine this intersection
  159.      * are prohibitively expensive.
  160.      * </ul>
  161.      * This means that this method might return <code>true</code> even
  162.      * though the <code>Rectangle2D</code> does not intersect the
  163.      * <code>Shape</code>. 
  164.      * @param r the specified <code>Rectangle2D</code>
  165.      * @return <code>true</code> if the interior of the <code>Shape</code> and  
  166.      *         the interior of the specified <code>Rectangle2D</code>
  167.      *        intersect, or are both highly likely to intersect and intersection
  168.      *        calculations would be too expensive to perform; <code>false</code>
  169.      *         otherwise.
  170.      * @see #intersects(double, double, double, double)
  171.      */
  172.     public boolean intersects(Rectangle2D r);
  173.  
  174.     /**
  175.      * Tests if the interior of the <code>Shape</code> entirely contains 
  176.      * the specified rectangular area.  All coordinates that lie inside
  177.      * the rectangular area must lie within the <code>Shape</code> for the
  178.      * entire rectanglar area to be considered contained within the 
  179.      * <code>Shape</code>.
  180.      * <p>
  181.      * This method might conservatively return <code>false</code> when:
  182.      * <ul>
  183.      * <li>
  184.      * the <code>intersect</code> method returns <code>true</code> and
  185.      * <li>
  186.      * the calculations to determine whether or not the
  187.      * <code>Shape</code> entirely contains the rectangular area are
  188.      * prohibitively expensive.
  189.      * </ul>
  190.      * This means that this method might return <code>false</code> even
  191.      * though the <code>Shape</code> contains the rectangular area.
  192.      * The <code>Area</code> class can be used to perform more accurate 
  193.      * computations of geometric intersection for any <code>Shape</code>
  194.      * object if a more precise answer is required.
  195.      * @param x, y the coordinates of the specified rectangular area
  196.      * @param w the width of the specified rectangular area
  197.      * @param h the height of the specified rectangular area
  198.      * @return <code>true</code> if the interior of the <code>Shape</code>
  199.      *         entirely contains the specified rectangular area;
  200.      *         <code>false</code> otherwise or, if the <code>Shape</code>    
  201.      *        contains the rectangular area and the   
  202.      *        <code>intersects</code> method returns <code>true</code> 
  203.      *         and the containment calculations would be too expensive to
  204.      *         perform.
  205.      * @see java.awt.geom.Area
  206.      * @see #intersects
  207.      */
  208.     public boolean contains(double x, double y, double w, double h);
  209.  
  210.     /**
  211.      * Tests if the interior of the <code>Shape</code> entirely contains the 
  212.      * specified <code>Rectangle2D</code>.
  213.      * This method might conservatively return <code>false</code> when:
  214.      * <ul>
  215.      * <li>
  216.      * the <code>intersect</code> method returns <code>true</code> and
  217.      * <li>
  218.      * the calculations to determine whether or not the
  219.      * <code>Shape</code> entirely contains the <code>Rectangle2D</code>
  220.      * are prohibitively expensive.
  221.      * </ul>
  222.      * This means that this method might return <code>false</code> even   
  223.      * though the <code>Shape</code> contains the
  224.      * <code>Rectangle2D</code>.
  225.      * The <code>Area</code> class can be used to perform more accurate 
  226.      * computations of geometric intersection for any <code>Shape</code>  
  227.      * object if a more precise answer is required.
  228.      * @param r The specified <code>Rectangle2D</code>
  229.      * @return <code>true</code> if the interior of the <code>Shape</code>
  230.      *          entirely contains the <code>Rectangle2D</code>;
  231.      *          <code>false</code> otherwise or, if the <code>Shape</code>
  232.      *          contains the <code>Rectangle2D</code> and the
  233.      *          <code>intersects</code> method returns <code>true</code>
  234.      *          and the containment calculations would be too expensive to
  235.      *          perform. 
  236.      * @see #contains(double, double, double, double)
  237.      */
  238.     public boolean contains(Rectangle2D r);
  239.  
  240.     /**
  241.      * Returns an iterator object that iterates along the 
  242.      * <code>Shape</code> boundary and provides access to the geometry of the 
  243.      * <code>Shape</code> outline.  If an optional {@link AffineTransform}
  244.      * is specified, the coordinates returned in the iteration are
  245.      * transformed accordingly.
  246.      * <p>
  247.      * Each call to this method returns a fresh <code>PathIterator</code>
  248.      * object that traverses the geometry of the <code>Shape</code> object
  249.      * independently from any other <code>PathIterator</code> objects in use
  250.      * at the same time.
  251.      * <p>
  252.      * It is recommended, but not guaranteed, that objects 
  253.      * implementing the <code>Shape</code> interface isolate iterations
  254.      * that are in process from any changes that might occur to the original
  255.      * object's geometry during such iterations.
  256.      * <p>
  257.      * Before using a particular implementation of the <code>Shape</code> 
  258.      * interface in more than one thread simultaneously, refer to its 
  259.      * documentation to verify that it guarantees that iterations are isolated 
  260.      * from modifications.
  261.      * @param at an optional <code>AffineTransform</code> to be applied to the
  262.      *         coordinates as they are returned in the iteration, or 
  263.      *        <code>null</code> if untransformed coordinates are desired
  264.      * @return a new <code>PathIterator</code> object, which independently    
  265.      *        traverses the geometry of the <code>Shape</code>.
  266.      */
  267.     public PathIterator getPathIterator(AffineTransform at);
  268.  
  269.     /**
  270.      * Returns an iterator object that iterates along the <code>Shape</code>
  271.      * boundary and provides access to a flattened view of the
  272.      * <code>Shape</code> outline geometry.
  273.      * <p>
  274.      * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
  275.      * returned by the iterator.
  276.      * <p>
  277.      * If an optional <code>AffineTransform</code> is specified,
  278.      * the coordinates returned in the iteration are transformed
  279.      * accordingly.
  280.      * <p>
  281.      * The amount of subdivision of the curved segments is controlled
  282.      * by the <code>flatness</code> parameter, which specifies the
  283.      * maximum distance that any point on the unflattened transformed
  284.      * curve can deviate from the returned flattened path segments.
  285.      * Note that a limit on the accuracy of the flattened path might be
  286.      * silently imposed, causing very small flattening parameters to be
  287.      * treated as larger values.  This limit, if there is one, is
  288.      * defined by the particular implementation that is used.
  289.      * <p>
  290.      * Each call to this method returns a fresh <code>PathIterator</code>
  291.      * object that traverses the <code>Shape</code> object geometry 
  292.      * independently from any other <code>PathIterator</code> objects in use at
  293.      * the same time.
  294.      * <p>
  295.      * It is recommended, but not guaranteed, that objects 
  296.      * implementing the <code>Shape</code> interface isolate iterations
  297.      * that are in process from any changes that might occur to the original
  298.      * object's geometry during such iterations.
  299.      * <p>
  300.      * Before using a particular implementation of this interface in more
  301.      * than one thread simultaneously, refer to its documentation to
  302.      * verify that it guarantees that iterations are isolated from
  303.      * modifications.
  304.      * @param at an optional <code>AffineTransform</code> to be applied to the
  305.      *         coordinates as they are returned in the iteration, or 
  306.      *        <code>null</code> if untransformed coordinates are desired
  307.      * @param flatness the maximum distance that the line segments used to
  308.      *          approximate the curved segments are allowed to deviate
  309.      *          from any point on the original curve
  310.      * @return a new <code>PathIterator</code> that independently traverses 
  311.      *         the <code>Shape</code> geometry.
  312.     */
  313.     public PathIterator getPathIterator(AffineTransform at, double flatness);
  314. }
  315.